<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang xml:lang>
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <title>User Guide</title>
  <style type="text/css">
      code{white-space: pre-wrap;}
      span.smallcaps{font-variant: small-caps;}
      span.underline{text-decoration: underline;}
      div.column{display: inline-block; vertical-align: top; width: 50%;}
  </style>
  <style type="text/css">
html {
font-size: 100%;
overflow-y: scroll;
-webkit-text-size-adjust: 100%;
-ms-text-size-adjust: 100%;
}
body {
color: #444;
font-family: Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif;
font-size: 12px;
line-height: 1.7;
padding: 1em;
margin: auto;
max-width: 42em;
background: #fefefe;
}
a {
color: #0645ad;
text-decoration: none;
}
a:visited {
color: #0b0080;
}
a:hover {
color: #06e;
}
a:active {
color: #faa700;
}
a:focus {
outline: thin dotted;
}
*::-moz-selection {
background: rgba(255, 255, 0, 0.3);
color: #000;
}
*::selection {
background: rgba(255, 255, 0, 0.3);
color: #000;
}
a::-moz-selection {
background: rgba(255, 255, 0, 0.3);
color: #0645ad;
}
a::selection {
background: rgba(255, 255, 0, 0.3);
color: #0645ad;
}
p {
margin: 1em 0;
}
img {
max-width: 100%;
}
h1, h2, h3, h4, h5, h6 {
color: #111;
line-height: 125%;
margin-top: 2em;
font-weight: normal;
}
h4, h5, h6 {
font-weight: bold;
}
h1 {
font-size: 2.5em;
}
h2 {
font-size: 2em;
}
h3 {
font-size: 1.5em;
}
h4 {
font-size: 1.2em;
}
h5 {
font-size: 1em;
}
h6 {
font-size: 0.9em;
}
blockquote {
color: #666666;
margin: 0;
padding-left: 3em;
border-left: 0.5em #EEE solid;
}
hr {
display: block;
height: 2px;
border: 0;
border-top: 1px solid #aaa;
border-bottom: 1px solid #eee;
margin: 1em 0;
padding: 0;
}
pre, code, kbd, samp {
color: #000;
font-family: monospace, monospace;
_font-family: 'courier new', monospace;
font-size: 0.98em;
}
pre {
white-space: pre;
white-space: pre-wrap;
word-wrap: break-word;
}
b, strong {
font-weight: bold;
}
dfn {
font-style: italic;
}
ins {
background: #ff9;
color: #000;
text-decoration: none;
}
mark {
background: #ff0;
color: #000;
font-style: italic;
font-weight: bold;
}
sub, sup {
font-size: 75%;
line-height: 0;
position: relative;
vertical-align: baseline;
}
sup {
top: -0.5em;
}
sub {
bottom: -0.25em;
}
ul, ol {
margin: 1em 0;
padding: 0 0 0 2em;
}
li p:last-child {
margin-bottom: 0;
}
ul ul, ol ol {
margin: .3em 0;
}
dl {
margin-bottom: 1em;
}
dt {
font-weight: bold;
margin-bottom: .8em;
}
dd {
margin: 0 0 .8em 2em;
}
dd:last-child {
margin-bottom: 0;
}
img {
border: 0;
-ms-interpolation-mode: bicubic;
vertical-align: middle;
}
figure {
display: block;
text-align: center;
margin: 1em 0;
}
figure img {
border: none;
margin: 0 auto;
}
figcaption {
font-size: 0.8em;
font-style: italic;
margin: 0 0 .8em;
}
table {
margin-bottom: 2em;
border-bottom: 1px solid #ddd;
border-right: 1px solid #ddd;
border-spacing: 0;
border-collapse: collapse;
}
table th {
padding: .2em 1em;
background-color: #eee;
border-top: 1px solid #ddd;
border-left: 1px solid #ddd;
}
table td {
padding: .2em 1em;
border-top: 1px solid #ddd;
border-left: 1px solid #ddd;
vertical-align: top;
}
.author {
font-size: 1.2em;
text-align: center;
}
@media only screen and (min-width: 480px) {
body {
font-size: 14px;
}
}
@media only screen and (min-width: 768px) {
body {
font-size: 16px;
}
}
@media print {
* {
background: transparent !important;
color: black !important;
filter: none !important;
-ms-filter: none !important;
}
body {
font-size: 12pt;
max-width: 100%;
}
a, a:visited {
text-decoration: underline;
}
hr {
height: 1px;
border: 0;
border-bottom: 1px solid black;
}
a[href]:after {
content: " (" attr(href) ")";
}
abbr[title]:after {
content: " (" attr(title) ")";
}
.ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after {
content: "";
}
pre, blockquote {
border: 1px solid #999;
padding-right: 1em;
page-break-inside: avoid;
}
tr, img {
page-break-inside: avoid;
}
img {
max-width: 100% !important;
}
@page :left {
margin: 15mm 20mm 15mm 10mm;
}
@page :right {
margin: 15mm 10mm 15mm 20mm;
}
p, h2, h3 {
orphans: 3;
widows: 3;
}
h2, h3 {
page-break-after: avoid;
}
}
</style>
</head>
<body>
<header id="title-block-header">
<h1 class="title">User Guide</h1>
</header>
<hr />
<h3 id="overview">Overview</h3>
<p>vShell is a virtual shell environment application for the Android OS. It provides a virtual machine running small Linux distribution ready for the use out-of-box.</p>
<p>Here are some details on the virtual machine configuration:</p>
<ul>
<li>CPU: emulated 1-core x86 64-bit.</li>
<li>RAM: 32% of host memory + 8% for QEMU TCG buffers.</li>
<li>HDD: 64 GB, has a default 4 GB partition for user data.</li>
<li>Host storage: via 9P FS, mount tag <code>host_storage</code>.</li>
<li>Network: user-mode via SLiRP.</li>
<li>Operating system: <a href="https://alpinelinux.org/">Alpine Linux</a>.</li>
</ul>
<p>Please note that provided default setup of the Alpine Linux is diskless. The whole operating system is copied into RAM, which takes about 40 MB. All changes are discarded unless were saved to the disk with the utility <a href="https://wiki.alpinelinux.org/wiki/Alpine_local_backup">lbu</a>. In order to change this behavior, you will need to format HDD and re-install the system from scratch, which could be easily done via ‘setup-alpine’ utility.</p>
<p><strong>Disclaimer</strong>: neither vShell application nor its author is affiliated with the <a href="https://alpinelinux.org/">Alpine Linux</a> project. Operating system is provided as-is and vShell author is not responsible about bugs in the software packages.</p>
<p><em>This guide does not cover Shell Scripting and Linux System Administration topics.</em></p>
<hr />
<h3 id="user-interface">User interface</h3>
<h4 id="terminal">Terminal</h4>
<p>vShell application uses the XTerm-compatible terminal emulator as a frontend for a serial console of the virtual machine. It has a True Color support and uses Inconsolata LGC font patched by Nerd-Fonts for additional glyphs support.</p>
<p><span style="display:block;text-align:center"> <img alt="vShell session" src="" style="width:90%;max-width:700px;"> </span></p>
<p>The application does not provide a way for customizing the terminal style like a color scheme or the font, because chosen defaults are considered as suitable for the most configurations.</p>
<p>The terminal reacts to the following kinds of a user input:</p>
<ul>
<li>A pinch-zooming gesture to scale the text size.</li>
<li>A long tap to start text selection or open a context menu.</li>
<li>A single tap to emulate a mouse left button click.</li>
</ul>
<p>Please note that this application is intended to have only one terminal session by design. To have more, you will need to use a terminal multiplexer like <code>tmux</code>.</p>
<h5 id="troubleshooting-terminal-has-stuck">Troubleshooting: terminal has stuck</h5>
<p>The terminal is sensitive to printed data. If a binary content has been accidentally printed or some misbehaving program incorrectly initialized the console, it can be easily messed up.</p>
<p>In this case, you need to either execute the command <code>reset</code> or tap a button <strong>Reset</strong> which is located in the context menu.</p>
<h5 id="troubleshooting-misplaced-text">Troubleshooting: misplaced text</h5>
<p>If you have re-scaled the text size, you may observe an incorrect line wrapping or misplaced UI elements of the console applications. That is happening due to the nature of the serial line, which does not support a screen size handshaking.</p>
<p><span style="display:block;text-align:center"> <img alt="Example of misplaced UI elements" src="" style="width:90%;max-width:700px;"> </span></p>
<p>To solve the issue, you need to use a command <code>resize</code> after changing the text scale. A default setup of the operating system provided by vShell application runs this command automatically in a preexec hook of Zsh shell.</p>
<h4 id="notification">Notification</h4>
<p>When the application has successfully started a foreground service, a notification will be shown. Clicking on the notification will open the terminal session. Expanding the notification would reveal some action buttons.</p>
<p><span style="display:block;text-align:center"> <img alt="Notification screenshot" src="" style="width:90%;max-width:700px;"> </span></p>
<p>Clicking on a button <strong>Acquire wakelock</strong> will prevent the device from going into the sleep mode. Use this action when you need to keep the virtual machine from being suspended when the screen is turned off.</p>
<p>Clicking on a button <strong>Shut down</strong> will immediately close the application. Shutting down the virtual machine by this way can lead to a loss of unsaved data, so be careful.</p>
<h4 id="keyboard">Keyboard</h4>
<h5 id="touch-keyboard-shortcuts">Touch keyboard shortcuts</h5>
<p><strong>Volume Down</strong> key emulates the <strong>Ctrl</strong> key which can be combined with others to request a special action. The possible key combinations are the software-specific. To learn about them, consult with a documentation of your installed packages.</p>
<p><strong>Volume Up</strong> key produces a certain input in the following combinations:</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Key combination</th>
<th style="text-align: left;">Produced input</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><code>Volume-Up .</code></td>
<td style="text-align: left;"><code>Ctrl \</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>Volume-Up &lt;1..9&gt;</code></td>
<td style="text-align: left;"><code>F1</code>, <code>F2</code>, …, <code>F9</code> keys</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>Volume-Up 0</code></td>
<td style="text-align: left;"><code>F10</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>Volume-Up A</code></td>
<td style="text-align: left;">Left arrow key</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>Volume-Up B</code></td>
<td style="text-align: left;"><code>Alt B</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>Volume-Up D</code></td>
<td style="text-align: left;">Right arrow key</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>Volume-Up E</code></td>
<td style="text-align: left;">Escape</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>Volume-Up F</code></td>
<td style="text-align: left;"><code>Alt F</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>Volume-Up H</code></td>
<td style="text-align: left;"><code>~</code>, the tilde character</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>Volume-Up K</code></td>
<td style="text-align: left;">Toggle extra keys row</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>Volume-Up L</code></td>
<td style="text-align: left;"><code>|</code>, the pipe character</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>Volume-Up N</code></td>
<td style="text-align: left;">Page down key</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>Volume-Up P</code></td>
<td style="text-align: left;">Page up key</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>Volume-Up S</code></td>
<td style="text-align: left;">Down arrow key</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>Volume-Up T</code></td>
<td style="text-align: left;">Tab key</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>Volume-Up U</code></td>
<td style="text-align: left;"><code>_</code>, the underscore character</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>Volume-Up V</code></td>
<td style="text-align: left;">Show the volume control</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>Volume-Up W</code></td>
<td style="text-align: left;">Up arrow key</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>Volume-Up X</code></td>
<td style="text-align: left;"><code>Alt X</code></td>
</tr>
</tbody>
</table>
<p>Note that <strong>Volume Up</strong> does not represent the <strong>Alt</strong> key even though it is being used to emulate certain its combinations.</p>
<h5 id="hardware-keyboard-shortcuts">Hardware keyboard shortcuts</h5>
<p>These key combinations can be used on a hardware keyboard to trigger certain actions of the application:</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Key combination</th>
<th style="text-align: left;">Action</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><code>Ctrl Alt +</code></td>
<td style="text-align: left;">Increase text size</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>Ctrl Alt -</code></td>
<td style="text-align: left;">Reduce text size</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>Ctrl Alt K</code></td>
<td style="text-align: left;">Toggle the touch keyboard</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>Ctrl Alt M</code></td>
<td style="text-align: left;">Open context menu</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>Ctrl Alt U</code></td>
<td style="text-align: left;">Open URL selector</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>Ctrl Alt V</code></td>
<td style="text-align: left;">Paste clipboard</td>
</tr>
</tbody>
</table>
<h5 id="extra-keys-row">Extra Keys Row</h5>
<p>Extra Keys Row is a widget displayed above the touch keyboard. It provides special keys that are commonly used by console programs.</p>
<p><span style="display:block;text-align:center"> <img alt="Extra keys row screenshot" src="" style="width:90%;max-width:700px;"> </span></p>
<p>Swiping up some keys will expose the alternate ones. Particularly:</p>
<ul>
<li><code>-</code> will show a key for <code>_</code></li>
<li><code>|</code> will show a key for <code>&amp;</code></li>
</ul>
<p>You may toggle the Extra Keys Row with a key combination <strong>Volume Up+K</strong>.</p>
<h3 id="port-forwarding">Port forwarding</h3>
<p>QEMU is configured to expose the guest port 80 as the random port on local host. The primary purpose is acessing the local web services with taking advantage of a web browser installed on your host.</p>
<p>The application context menu provides an address which can be used for accessing the guest server as well as a shortcut for opening the web browser with correct URL.</p>
<p><span style="display:block;text-align:center"> <img alt="Context menu screenshot" src="" style="width:90%;max-width:700px;"> </span></p>
<p>Please note that forwarded port is accessible only on the local host. The application does not expose it to the local network or the Internet. If you wish to make your server accessible outside, consider using the port external forwarding services or relays.</p>
<p>vShell comes without any server software installed. You have to install and configure the server on your own. Just make sure it listens for incoming connections on the port 80.</p>
<hr />
<p style="text-align:center;">
<font size="1dp"><i>vShell — a virtual shell environment application.</i></font>
</p>
</body>
</html>
